---
title: API
---

# API

## `theme-ui`

The core `theme-ui` package exports the following modules.

### `/jsx-runtime`

While not being available in the `theme-ui` package directly, there are two
separate entry points for React create element functions intended to be used in
the
[automatic JSX runtime](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html)
with a custom pragma comment. They add support for the `sx` prop, which uses
Emotion's create element functions internally and parse style objects with the
Theme UI `css` utility.

**Usage:**

```jsx
/** @jsxImportSource theme-ui */

export default (props) => (
  <div
    {...props}
    sx={{
      color: 'primary',
    }}
  />
)
```

**Imports for use without JSX:**

```js
import { jsx, jsxs } from 'theme-ui/jsx-runtime'
import { jsxDEV } from 'theme-ui/jsx-dev-runtime'
```

### `ThemeUIProvider`

The `ThemeUIProvider` component is a wrapper around Emotion's `ThemeUIProvider`
and MDX's `MDXProvider`. It provides default styled components to MDX content
that pick up values from `theme.styles`. It also handles color mode state.

| Prop         | Type   | Description                    |
| ------------ | ------ | ------------------------------ |
| `theme`      | Object | Theming context object         |
| `components` | Object | Optional custom MDX components |
| `children`   | Node   | React children                 |

### `useThemeUI`

The `useThemeUI` hook returns the full Theme UI context object, which includes
`theme`, and color mode.

```js
const context = useThemeUI()
const { theme, components, colorMode, setColorMode } = context
```

### `useColorMode`

The `useColorMode` hook returns an array with two values: the current color mode
state and an updater function. The color mode state can be any string and should
match the name of a color mode defined in `theme.colors.modes` or be a name for
the default color mode.

```js
const [colorMode, setColorMode] = useColorMode()
```

### `BaseStyles`

The `BaseStyles` component can be used to style child content that isn’t
generated from MDX. This can be useful with content from a CMS or Markdown.

<Note>

Note that this will increase the CSS specificity of child elements, and you may
run into issues with the cascade (i.e. specificity) when using this component.
This component should _not_ be used at the root of your application, as it will
override custom & component styling.

</Note>

```jsx
<BaseStyles>
  <h1>
    Styled based on <code>theme.styles</code>
  </h1>
</BaseStyles>
```

### `Context`

The React context used in Theme UI.

### `css`

As an alternative to using the `sx` prop, the `css` utility is intended for use
with the Emotion `css` prop. It will attempt to use values from the `theme`
object for many common CSS properties, and will fall back to raw values when
there is no corresponding theme value.

To see a list of supported CSS properties, see the [`sx` prop docs](/sx-prop).

```js
css(styleObject)(theme)
```

**Usage:**

```jsx
<div css={css(styles)} />
```

| Argument      | Type   | Description                                                                                          |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------- |
| `styleObject` | Object | a theme-aware style object with support for responsive array values and Styled System prop shortcuts |
| `theme`       | Object | the Emotion theming context object                                                                   |

### `get`

An existential getter function used internally to extract a field (or object)
from a theme object.

### `getObjectWithVariants`

Similar to the `get` function above, but will also resolve any `variant` field
if found inside the object.

### `merge`

A function to deeply merge themes.

**Usage**

```jsx
import dark from '@theme-ui/preset-dark'

const theme = merge(dark, {
  fontWeights: {
    body: 500,
    heading: 700,
    bold: 900,
  },
})
```

### `InitializeColorMode`

this component can be rendered in HTML before the main application to help
prevent the flash of colors that can occur during rehydration.

**Usage**

```jsx
<InitializeColorMode />
```

This component is used internally by
[`gatsby-plugin-theme-ui`](/packages/gatsby-plugin), but if you’re using Next.js
or another React framework with static or server-side rendering, you’ll want to
add it to the root level of your application.

## Components

For component API docs, see [Components](/components).

[styled-system/css]: https://styled-system.com/css
